BigDFT.Calculators module

This module defines some classes to perform a calculation using BigDFT using binding (GIBinding) or using system call (SystemCalculator).

class GIBinding

Calculator for BigDFT from Gobject Introspection bindings.

class Runner(**kwargs)

Run of something.

This object is associated with the concept of execution of a action. It may be customized to be used inside workflows and datasets. The central functionality is the run method that can be customized on subclasses of Runner. In this object there are global and local options of a run method. All arguments passed at the instantiation are stored as global options. For each call to run, these global options may updated by the arguments of the run call.

Parameters:

**kwargs – global options of the runner. Deepcopied in the dictionary returned by global_options().

Example

>>> torun=Runner(args1='one',args2='two')
>>> print(torun.global_options())
{'args1':'one','args2':'two'}
>>> print(torun.get_global_option('args1'))
'one'

global_options()

Get all global options dict.

Returns:

The dictionary of the global options in its current status

Return type:

dict

get_global_option(key)

Get one key in global options. The key must exist. Useful to force implementation of compulsory options when subclassing.

Parameters:

key (string) – the global option key

Returns:

The value of the global options labelled by key

update_global_options(**kwargs)

Update the global options by providing keyword arguments.

Parameters:

**kwargs – arguments to be updated in the global options

pop_global_option(key)

Remove a given global option from the global option dictionary

Parameters:

key (string) – the global option key

Returns:

The value of the global option

run(**kwargs)

Run method of the class. It performs the following actions:

• Constructs the local dictionary to be passed as **kwargs to the process_run function;

• Calls the pre_processing() method (intended to prepare some actions associated to the process_run() method);

• Calls process_run() with the dictionary returned by pre_processing() as **kwargs;

• Update such dictionary with the results returned by process_run() and call post_processing();

• Returns the object passed by the call to post_processing() class method

Developers are therefore expected to override pre_processing() process_run() and post_processing(), when subclassing Runner.

pre_processing()

Pre-treat the keyword arguments and the options, if needed.

Returns:

dictionary of the pre-treated keyword arguments that have to be actually considered by process_run.

Return type:

dict

process_run(**kwargs)

Main item of the runner, defines the information that have to be post_processed by post_processing.

Parameters:

**kwargs (dict) – keyword arguments as returned from the pre_processing() method.

Returns:

dictionary objects to be passed to post_processing, once the dictionary returned by pre_processing() has been updated

Return type:

dict

post_processing(**kwargs)

Post-processing, take the arguments as they are provided by the update of process_run() and pre_processing() methods.

Returns:

The final object that each call to the run() method is supposed to provide.

class SystemCalculator(omp='1', mpi_run='', dry_run=False, skip=False, verbose=True)

Define a BigDFT calculator.

Main calculator of BigDFT code. It performs os.system() calls to the main bigdft executable in the $BIGDFT_ROOT directory. It is designed for two purposes:

• Run the code in a workstation-based environment, for example within notebooks or scripts.

• Run the code from a python script that is submitted to a batch scheduler in a potnentially large-scale supercomputer.

For triggering the execution, this code gets two variables from the

environment:

• The value of OMP_NUM_THREADS to set the number of OMP_NUM_THREADS. If this variable is not present in the environment, SystemCalculator sets it to the value provided by the omp keyword at initialization.

• The value of BIGDFT_MPIRUN to define the MPI execution command. If absent, the run is executed simply by $BIGDFT_ROOT/bigdft, followed by the command given by post-processing.

Parameters:

• omp (int) – number of OpenMP threads. It defaults to the $OMP_NUM_THREADS variable in the environment, if present, otherwise it fixes the run to 1 thread.

• mpi_run (str) – define the MPI command to be used. It defaults to the value $BIGDFT_MPIRUN of the environment, if present. When using this calculator into a job submission script, the value of $BIGDFT_MPIRUN variable may be set appropriately to launch the bigdft executable.

• skip (bool) – if True, do not run the calculation if the corresponding logfile exists.

• verbose (bool) – if True the class prints out informations about the operations that are being performed by the calculator

• dry_run (bool) – check the input, estimate the memory but do not perform the calculation.

• dry_mpi (int) – Number of MPI processes for the estimation of the memory when dry_run is True (not yet implemented)

• taskgroup_size (int) – number of MPI processes of each of the taskgroup in the case of a runs_file.

Warning

At the initialization, SystemCalculator checks if the environment

variable $BIGDFT_ROOT is defined.

This would mean (although not guarantee) that the environment has been

properly set prior to the evaluation of the python command.

Also, it checks that the executable file bigdft might be found in

the $BIGDFT_ROOT/bigdft path.

Example

>>> inpdict = { 'dft': { 'ixc': 'LDA' }} #a simple input file
>>> study = SystemCalculator(omp=1)
>>> logf = study.run(name="test",input=inpdict)
Executing command:  $BIGDFT_MPIRUN <path_to_$BIGDFT_ROOT>/bigdft test

run(name='', run_dir='.', outdir='', run_names='', input=None, posinp='posinp.xyz')

Run a calculation building the input file from a dictionary.

Parameters:

• name (str) – naming scheme of the run i.e. <name>.yaml is the input file and log-<name>.yaml the output one. Data will then be written in the directory data-<name>.yaml, unless the “radical” keyword is specified in the input dictionary.

• run_dir (str) – specify the directory where bigdft will be

• executed (the input and log file will be created in it) – It can be a recursive directory path.

• outdir (str) – specify the output directory for all data coming from bigdft

• run_names (str) – File containing the list of the run ids which have to be launched independently (list in yaml format). This option is not compatible with the name option.

• input (dict) – give the input parameters (a

• is (dictionary or a list of dictionary) If this parameter) – absent it is assumed that an inputfile named name.yaml exists in the directory indicated by run_dir

• posinp (file or dict) – indicate the posinp file (atomic position file). It can be either a path or a dictionary in the yaml format.

• sys (BigDFT.Systems.System) – a system class for providing the atomic data.

Returns:

Instance of the logfile associated to the run. associated to the run which has been just performed. If the run failed for some reasons, the logfile seem not existing or it cannot be parsed it returns None.

Return type:

Logfile

Raises:

• ValueError – if the logfile does not exists or is not

• accessible, or if the posinp file does not exists –

Todo

Set the return value of run in the case of a run_file. It should be a list of Logfile classes

os = <module 'os' from '/usr/local/anaconda/lib/python3.7/os.py'>

shutil = <module 'shutil' from '/usr/local/anaconda/lib/python3.7/shutil.py'>

pre_processing()

Process local run dictionary to create the input directory and identify the command to be passed

Returns:

dictionary containing the command to be passed to process_run()

Return type:

dict

process_run(command)

Finally launch the code.

Routine associated to the running of the bigdft executable.

Parameters:

command (str) – the command as it is set by the pre_processing method.

Returns:

The dictionary containing timedbg and logname

values to be passed to post_processing function

Return type:

dict

post_processing(timedbg, logname, command)

Check the existence and the log file and return an instance logfile.

Returns:

(Logfile) Instance of the logfile associated to the run. associated to the run which has been just performed. If the run failed for some reasons, the logfile seem not existing or it cannot be parsed it returns None.

Raises:

ValueError – if the logfile does not exists or is not accessible

Todo

Set the return value of run in the case of a run_file. It should be a list of Logfile classes

class DummyCalculator(omp='1', mpi_run='', dry_run=False, skip=False, verbose=True)

!skip

False calculator for testing RemoteRunner functionality.

To be used on systems where BigDFT is either not installed, or it is inconvenient to do so. Purely for development and/or testing purposes

os = <module 'os' from '/usr/local/anaconda/lib/python3.7/os.py'>

shutil = <module 'shutil' from '/usr/local/anaconda/lib/python3.7/shutil.py'>

pre_processing()

!skip

generates run_args not needed for a dummy run

process_run(**kwargs)

!skip

dummy process_run function, simply have to update the ‘run’ flag

post_processing(**kwargs)

!skip

this is what actually gets returned from Run()